Usenet 1993 July

home *** CD-ROM | disk | FTP | other *** search

/ Usenet 1993 July / InfoMagic USENET CD-ROM July 1993.ISO / answers / news-answers / guidelines next >

Wrap

Internet Message Format | 1993-06-19 | 26.8 KB

Path: senator-bedfellow.mit.edu!enterpoop.mit.edu!pad-thai.aktis.com!GZA.COM!jik From: jik@GZA.COM (Jonathan I. Kamens) Newsgroups: news.answers,alt.answers,comp.answers,misc.answers,rec.answers,sci.answers,soc.answers,talk.answers Subject: *.answers submission guidelines Supersedes: <news-answers/guidelines_737960404@GZA.COM> Followup-To: poster Date: 20 Jun 1993 01:00:08 -0400 Organization: Geer Zolot Associates Lines: 583 Approved: news-answers-request@MIT.Edu (Jonathan I. Kamens) Distribution: world Expires: 3 Aug 1993 05:00:07 GMT Message-ID: <news-answers/guidelines_740552407@GZA.COM> Reply-To: news-answers-request@MIT.Edu (Jonathan I. Kamens) NNTP-Posting-Host: pad-thai.aktis.com Xref: senator-bedfellow.mit.edu news.answers:9588 alt.answers:443 comp.answers:1054 misc.answers:110 rec.answers:1254 sci.answers:267 soc.answers:257 talk.answers:31 Archive-name: news-answers/guidelines Version: $Id: guidelines,v 1.60 1993/06/09 15:42:49 jik Exp $ In order to submit an FAQ posting to the news.answers newsgroup (and to zero or more of the other *.answers newsgroups (alt.answers, comp.answers, misc.answers, rec.answers, sci.answers, soc.answers, talk.answers) along with it), you should first modify your posting to conform to the guidelines given below, in section I. Then, you should submit your posting to me using the instructions given below, in section II. Once your posting is approved, you will post it directly to news.answers and other newsgroups yourself; i.e., after approval, you no longer have to go through me at all to post. This is explained in more detail below. I. Submission guidelines A. Why the guidelines? There are three main reasons for the guidelines: 1. Appropriateness Only periodic informational postings that are intended to be read by people belong in news.answers. The guidelines are meant to prevent other types of postings, including discussion of periodic informational postings, from appearing in the group. 2. Usefulness to people The newsgroup should be as useful as possible to the people who read it. Requirements such as effective "Subject:" and "Summary:" lines (see below) further this goal. 3. Automatic archiving One of the main points of news.answers is that it can be archived automatically in order to build up a database of periodic informational postings. Requirements such as the "Archive-name:" line further that goal. B. Required header fields There are two "headers" in a news.answers posting. The first is the normal header that any article posted to the USENET has. The second header, the "auxiliary header," is separated from the first by one or more blank lines. As far as the News software is concerned, the auxiliary header is just part of the body of the article; however, news.answers requires some information in it. The requirements for each of the two headers are discussed in detail below. Required headers are marked with "(Required)", while optional ones are marked with "(Optional)". 1. The normal header a. Newsgroups (Required) I need to know exactly what will appear in the Newsgroups line of the posting. In addition to news.answers, your posting should be cross-posted to the other *.answers newsgroups of hierarchies in which it is posted. For example, a posting that is normally posted in both rec.music.makers.synth and comp.sys.ibm.pc.soundcard should be postded to both rec.answers and comp.answers in addition to news.answers. Note that postings to any of the *.answers newsgroups MUST be posted in news.answers, regardless of what other *.answers newsgroups they also appear in. Although the order of newsgroups on the line is not important from the point of view of the news software, I prefer to have news.answers listed last, since it is the least "relevant" of the listed newsgroups. The other *.answers newsgroups should be listed directly before news.answers. Example: Newsgroups: comp.sys.foo,comp.answers,news.answers Note that your Newsgroups line should NOT contain only *.answers groups. FAQ postings should be cross-posted to *.answers from their home newsgroups, rather than being posted separately to *.answers. However, if you get approval for *.answers cross-posting in the middle of your "posting cycle," and you do not wish to wait until the next scheduled posting time to cross-post to *.answers, then you can post your FAQ only to *.answers. If you choose to do this, please make sure to let me know you are going to, and please do not do it more than once. b. Subject (Required) The subject line of your posting should have some meaning outside of its home newsgroup(s). For example, instead of just "FAQ," you might have "<x> FAQ", where "<x>" is the name of the newsgroup or the topic being discussed. Furthermore, important information should appear near the beginning of the subject line, so that news readers that display article summaries don't cut off the important information. For example, instead of "Frequently Asked Questions about <x>," use "<x> Frequently asked Questions." Example: Subject: comp.sys.foo Frequently Asked Questions (FAQ) c. Followup-To (Required) and Reply-To (Optional) Your posting must have a "Followup-To:" line in the header that directs followups to somewhere other than *.answers. You may choose to direct followups back to the home newsgroup(s) of the FAQ, or to direct followups to the author of the FAQ, in which case "Followup-To: poster" is sufficient. That means that you actually put the word "poster" there, as specified in the RFC which describes the format of Usenet postings. Do NOT put an E-mail address in the "Followup-To:" field. If you forget the "Followup-To:" and I get mailed followups to your FAQ, I'm going to get peeved at you. Furthermore, your posting must have a valid E-mail reply address in the header, either in the "From:" field, or if not in "From:" then in "Reply-To:". Example: From: guru@foosys.com (Joe R. Programmer) Followup-To: comp.sys.foo Reply-To: faq-mail@foosys.com (FAQ Comments address) In this example, "guru" apparently wants mail about the FAQ to go to a different address than the rest of his mail. I've shown the "From:" header, because the version of the FAQ that you forward to me should show the "From:" header just as it will appear when the article is actually posted. d. Supersedes, Expires, References (Optional) It is a good idea to use "Supersedes:" and "Expires:" header lines to make sure that each version of your FAQ stays around until the next time it is posted. A useful tool for this is my Perl FAQ poster. It is available from rtfm.mit.edu, via anonymous ftp in the file /pub/post_faq/post_faq.shar, or via mail server (send mail to mail-server@rtfm.mit.edu with "send post_faq/post_faq.shar" in the body). Post_faq takes an article with its static headers (i.e., the headers that don't change each time the article is posted) included, adds dynamic headers to it, and posts the article. Another utility, Ian Kluft's AUTO-FAQ package (which is also written in Perl) provides more functionality, including automatic splitting of large FAQs into multi-part postings. If you're looking for something with a high level of automation to assist you in your FAQ maintenance and posting, you might want to try AUTO-FAQ instead of post_faq. It's available via anonymous ftp in ftp.amdahl.com:pub/faq/auto-faq.shar.Z. Furthermore, if you are posting a multi-part FAQ posting or a series of related FAQ postings, it is a good idea to add a "References:" line to all of the postings except the first one, making the contents of that line the Message-ID of the first posting in the series. If you do this, then people who use threaded news readers will be able to manipulate the entire series as a single thread, including (for example) killing the entire thread if they're not interested or saving the entire thread to a file with one command. The perl FAQ poster mentioned above supports an option for doing this. Example: Expires: Fri, 1 May 1992 00:00:00 GMT Supersedes: <foo-faq_701650000@foosys.com> The date in the "Expires:" header should be far enough into the future that a new version of the FAQ will be posted before the one you're posting now expires. I've shown both headers in the format my post_faq script would use. I haven't shown a "References:" header, since the example posting I've been presenting is not part of a multi-part FAQ; if there were a "References:" header, it would contain a Message ID just like the "Supersedes:" header. e. Summary (Optional) You are encouraged to put a summary of the contents of your article in the Summary field of the header. Try to describe what your FAQ discusses, and aim your description at someone who may not actually be directly interested in the topic covered by your FAQ. There have been discussions about using the Summary fields of the FAQ postings in news.answers to construct a short "catalog" of the information available through news.answers, so think of the Summary field as a "catalog entry" for your FAQ. Note that header fields (except for the Newsgroups field) are allowed to span multiple lines, as long as the continuation lines after the first start with whitespace (at least one space or tab character). Example: Summary: This posting contains a list of Frequently Asked Questions (and their answers) about Foo computers. It should be read by anyone who wishes to post to the comp.sys.foo newsgroup. 2. The auxiliary header The auxiliary header looks like the main message header (i.e. "Field-name: field-value"), but is separated from the main message header by a blank line, as well as followed by a blank line separating it from the rest of the body of the message. The auxiliary header of this posting is: Archive-name: news-answers/guidelines Version: $Id: guidelines,v 1.60 1993/06/09 15:42:49 jik Exp $ a. Archive-name (Required) In order to be cross-posted in news.answers, your posting must include an auxiliary archival header with an "Archive-name:" field. The purpose of the archive name is two-fold. First of all, it specifies where the FAQ should be stored in archives of the news.answers newsgroup. Second, it should give people, even people who do not read the home newsgroup of the FAQ, a pretty good idea of what's in it. Therefore, abbreviations which will only be recognized by people already familiar with the topic covered by the FAQ should be avoided if possible. The archive name should be composed of one or more one-word (i.e., no spaces) components, separated by slashes. Each component should be 14 characters or less in length, if at all possible; if not, then it should be unique in the first 14 characters (i.e., two archive names should never be identical after their components are all truncated to 14 characters). Avoid periods in the archive name, because some operating systems choke on them; if you must have word separators, use hyphens or underscores rather than periods. The archive namespace is hierarchical; for example, there are a number of lists of bookstores in the "books/stores" directory of the namespace, and all of their archive names start with "books/stores/". Multi-part FAQs should be named "name/part1", "name/part2", etc. Alternatively, if the parts of the FAQ are split by topic rather than by size, then you can use short topic names rather than "part1", "part2", etc. If you post a diff for your FAQ, it should be named "name/diff". If you post multiple diffs for a multi-part FAQ, they should be named "name/diff1", "name/diff2", etc. (if you want to use just one diff for a multi-part FAQ, you can just use "name/diff" as its name). If you post a diff to a one-part posting, then the original FAQ should be named "name/part1" (or "name/faq", or whatever else you think is appropriate, as long as I approve it) and the diff should be named "name/diff". Consider these examples: Topic Archive name(s) ----------------------------------- ------------------------------ comp.ai FAQ ai-faq/part1 ai-faq/part2 ai-faq/part3 rec.travel.air FAQs, various topics air-travel/bucket-shops air-travel/cheap-tickets/part1 air-travel/cheap-tickets/part2 air-travel/faq air-travel/jetlag-prevention air-travel/na-airport-codes air-travel/world-airport-codes soc.culture.esperanto FAQ esperanto-faq Please pick the archive name that you would like to use for your posting, and include the "Archive-name:" line with that archive name in it, when submitting to news.answers. If there is some problem with it, or if I would like to suggest an alternate name, I will let you know. Example: Archive-name: foo-faq If your posting already has an "Archive-name:" line which is not a valid news.answers archive name and you do not want to change it, or if you want the "Archive-name:" line you add to contain the name of a file in your own archives rather than in the news.answers archives, you can use a "News-answers-archive-name:" header line instead. b. Other archive names (Optional) The software which builds the FAQ archive on rtfm.mit.edu (see the "Introduction to the *.answers newsgroups" posting for more information about it) automatically uses the "Archive-name:" line to determine the file name in which to save an FAQ, when saving it in any of the "answers" newsgroups (news.answers, rec.aviation.answers, etc.). Furthermore, if you have a field of the form "Newsgroup-name-archive-name: name" in your FAQ's auxiliary header (see the example below), the specified archive name will be used to save in the specified newsgroup. Such a newsgroup-specific archive name overrides any generic "Archive-name:" line. When an archive name for an FAQ cannot be determined in either of the ways mentioned above, the Subject line of the posting (with some minor modifications) is used as its file name. For example, if you have this in your normal header: Newsroups: comp.foo,comp.bar,comp.answers,news.answers Subject: Comp.foo FAQ and this in your auxiliary header: Archive-name: foo-faq Comp-bar-archive-name: bar-faq then the posting will be saved as "foo-faq" in comp.answers and news.answers (because they are both "answers" newsgroups and will therefore use the Archive-name line), as "bar-faq" in comp.bar, and as "Comp.foo_FAQ" in comp.foo. If you do decide to specify additional archive names in your posting, please obey the guidelines for archive names given above. b. Last-modified, Version (Optional) You can have other fields in the auxiliary header, if you want. Two common ones are "Last-modified:" and "Version:". Example: Last-modified: 1992/03/25 Version: 2.5 3. Sample FAQ headers Putting together the examples I've given above, your FAQ's headers (or, at least, the ones you submit to me) might look like this: From: guru@foosys.com (Joe R. Programmer) Newsgroups: comp.sys.foo,comp.answers,news.answers Subject: comp.sys.foo FAQ Followup-To: comp.sys.foo Reply-To: faq-mail@foosys.com (FAQ Comments address) Summary: This posting contains a list of Frequently Asked Questions (and their answers) about Foo computers. It should be read by anyone who wishes to post to the comp.sys.foo newsgroup. Expires: Fri, 1 May 1992 00:00:00 GMT Supersedes: <foo-faq_701650000@foosys.com> Archive-name: foo-faq Last-modified: 1992/03/25 Version: 2.5 Note that the blank line separating the normal header from the auxiliary header must be completely blank, i.e., no tabs or spaces, and that there must also be one or more completely blank lines after the auxiliary header. Of course, you can include in the posting header any of the other standard USENET header fields that have not been discussed here. C. Posting frequency The frequency at which you choose to post your FAQ is left to your discretion. Some FAQ maintainers find that a monthly posting, with an Expires header to prevent each posting from going away before its replacement is posted, is sufficient. Some other newsgroups are so busy that a weekly posting of the FAQ is needed. Another possibility is to post the complete FAQ relatively infrequently, while posting a shorter pointer to it (e.g., providing instructions for getting it from archives) more frequently. If you choose to post your FAQ more frequently than once per month, you might want to consider not cross-posting it to *.answers every time you post. Although it may be necessary to post the FAQ in its home newsgroup often, it is probably not necessary to post it in *.answers as frequently. Note, however, that if you do this, you can't use Supersedes every time you post your FAQ, since a posting in just the FAQ's home newsgroup should not supersede the posting in both the home newsgroup and *.answers. Therefore, unless you're willing to have two copies of your FAQ in your home newsgroup at all times, you should always cross-post to *.answers (or use the system mentioned above, cross-posting the full FAQ to *.answers and a more frequent pointer posting just in its home newsgroup). When submitting your FAQ, please be sure to let me know the frequency at which you intend to post it to its home newsgroup, as well as the frequency at which you intend to cross-post it to *.answers (if different). D. Mailing lists for FAQ maintainers Maintainers of FAQs are strongly urged to join the faq-maintainers mailing list, which is used for discussion about the *.answers newsgroups and the maintenance of USENET FAQs. If you don't want to be on the discussion list, you may wish to join the faq-maintainers-announce list, which will be used only for announcements, instead. Note that subscribers to faq-maintainers automatically receive messages sent to faq-maintainers-announce. When submitting your FAQ, make sure to let me know whether or not you want to be on one of the lists. E. List of Periodic Informational Postings Unless you tell me otherwise, I will add any postings submitted to *.answers to the "List of Periodic Informational Postings" (LoPIP) articles which appear in news.answers, news.lists, and news.announce.newusers. If you do not have copies of the LoPIP postings and would like to get them, to see what they're like or to check if your FAQ is already listed, see the instructions at the end of this message. F. Article approval Once all of the other issues listed in this posting are resolved, you will be given approval to cross-post your FAQ to *.answers. You will have to indicate in the header of your posting that such approval has been given, or the posting will be mailed to me instead of posted. Note that I am intentionally being somewhat vague about what this entails. When I approve your posting for *.answers, I will provide more specific instructions. II. Submission instructions If you have a posting which you wish to submit to *.answers, you should first read the guidelines listed above and modify your posting to conform to them. Then, you should submit it by posting it to the news.answers newsgroup, assuming that the software on the poster's site works properly and will forward the posting to the news.answers moderator, or by mailing it to the news.answers submission address, news-answers@MIT.Edu. ONLY SUBMISSIONS SHOULD BE MAILED TO THAT ADDRESS. If there is some commentary or explanation that needs to be made, it should be mailed in a separate message to news-answers-request@MIT.Edu, which is the moderator contact address for any *.answers-related business. Please submit the FAQ in a form as close as possible to how it appears when you post it normally. This means that you should include a complete header, with at the very least the Subject line you normally use. I very much prefer you actually posting the message to news.answers as you would post it normally, including the cross-posted newsgroups, but omitting the moderation approval header line that would cause the article to actually be posted rather than mailed to me; this way, I will get to see exactly how the article will look when it is actually posted in news.answers. Also, if your FAQ does not say somewhere near the top how often it is posted, then please let me know the frequency in separate E-mail. Note that if you do not indicate moderator approval in the header of your posting, it will NOT be posted to any newsgroup, even if you list other newsgroups on the Newsgroups line besides *.answers groups. Therefore, you CAN and SHOULD place all Newsgroups to which you intend to post in the Newsgroups line, in the order you intend them to be in when you post. I will respond, by agreeing that the FAQ belongs in *.answers as-is, or by asking you to make minor modifications to it in order to make it acceptable, or by rejecting it as inappropriate for *.answers. If you are asked to make modifications, please do so and resubmit the posting to me just as you did the first time. Once an FAQ has been approved for *.answers, you will post it directly to the group yourself, by indicating in the header of the message that it was approved by the *.answers moderator, as described above. If possible, try to avoid posting your FAQ at a "predictable" time. For example, if you have decided to post it monthly, don't automatically decide to post it on the first of every month. This causes a flood of FAQs in *.answers (and on the net in general) at certain times of months, and this flood is big enough to overwhelm some smaller sites and many readers of *.answers. Therefore, rather than picking the "obvious" time to post, pick some other, random time during the month to do your posting. III. If you've submitted before If you've submitted FAQs to *.answers before, you still have to submit any new FAQs to me using the procedure described above, i.e., you cannot just post them directly to *.answers. This is also true if you add new parts to a multi-part posting, or if you convert a single posting into a multi-part posting. IV. Making changes to approved postings You should try to let me know if you change the Newsgroups or Subject line of a posting that you are cross-posting to *.answers, although this isn't very important and I probably won't have a heart attack if you forget or don't have time. You should definitely let me know if someone else takes over the maintenance of a posting that you've submitted. V. This posting Comments about, suggestions about or corrections to this posting are welcomed. If you would like to ask me to change this posting in some way, the method I appreciate most is for you to actually make the desired modifications to a copy of the posting, and then to send me the modified posting, or a context diff between my posted version and your modified version (if you do the latter, make sure to include in your mail the "Version:" line from my posted version). Submitting changes in this way makes dealing with them easier for me and helps to avoid misunderstandings about what you are suggesting. The following people provided feedback and helped to make this posting more readable and useful: Stan Brown <brown@NCoast.ORG> Aydin Edguer <edguer@alpha.CES.CWRU.Edu> Tom_Lane@G.GP.CS.CMU.EDU Cindy Tittle Moore <tittle@ics.uci.edu> Steven D. Ourada <sourada@iastate.edu> Ken Shirriff <shirriff@sprite.Berkeley.EDU> Dan Tilque <dant@logos.WR.TEK.COM> Bill Wohler <wohler@sap-ag.de> V. Getting the "List of Periodic Informational Postings" There are five "List of Periodic Informational Postings" postings: Subject: List of Periodic Informational Postings, Part 1/6 Subject: List of Periodic Informational Postings, Part 2/6 Subject: List of Periodic Informational Postings, Part 3/6 Subject: List of Periodic Informational Postings, Part 4/6 Subject: List of Periodic Informational Postings, Part 5/6 Subject: List of Periodic Informational Postings, Part 6/6 Newsgroups: news.lists,news.announce.newusers,news.answers They are available in the indicated USENET newsgroups, or via anonymous ftp from rtfm.mit.edu (18.70.0.224) in the files: /pub/usenet/news.answers/periodic-postings/part1 /pub/usenet/news.answers/periodic-postings/part2 /pub/usenet/news.answers/periodic-postings/part3 /pub/usenet/news.answers/periodic-postings/part4 /pub/usenet/news.answers/periodic-postings/part5 /pub/usenet/news.answers/periodic-postings/part6 They are also available from mail-server@rtfm.mit.edu by sending a mail message containing any or all of: send usenet/news.answers/periodic-postings/part1 send usenet/news.answers/periodic-postings/part2 send usenet/news.answers/periodic-postings/part3 send usenet/news.answers/periodic-postings/part4 send usenet/news.answers/periodic-postings/part5 send usenet/news.answers/periodic-postings/part6 If you want to find out more about the mail server, send a message to it containing "help".